Adopt Semi.Avalonia and a FieldWorks design-token system - #1083

This is the most consequential change in the queue, so it got the most scrutiny — including
running your scanner against fixtures rather than reading it. The token architecture is
right, and I want it to land.

What is good, plainly. Aliasing Semi's semantic tier instead of inventing a palette is
the correct default and the ADR argues it well. GenerateTokenKeys turning a stale key into
a compile error is the right instinct and is the thing that makes "no exceptions" mean
something. DialogTheme.axaml + DialogThemeBootstrap are extended in place rather than
replaced. Deleting FwCheckBoxStyle/FwRadioButtonStyle (454 lines) instead of porting them
is right, because Semi exposes those sizes as overridable resources. New strings go through
.resx with no new L10NSharp. No test constructs a WinForms Form. The four rejected
alternatives in the body are each argued with evidence rather than taste, and the
live-UI-language-switching investigation that concluded "don't build it" is exactly the kind
of negative result worth writing down.

Timing. Before this lands, Hasso, Zach and Ken need to verify the timing — this is
foundational to everything downstream of it, and the sequencing is their call as much as the
content is mine.

1. Pin the theme variant

Nothing in the branch sets RequestedThemeVariant. A whole-branch search for
RequestedThemeVariant|ThemeVariant|ActualThemeVariant returns exactly one hit:
FwThemeResources.cs:49 reading app.ActualThemeVariant. Under Avalonia 11.3.17
(Directory.Packages.props:186), an unset RequestedThemeVariant means ActualThemeVariant
follows the OS app-theme setting, so a machine in dark mode resolves the Dark dictionary —
the one FwColorTokens.axaml:77-78 labels "unreviewed first-pass placeholders, not
design-approved", while the PR body says Light is the only reviewed variant.

The reason this is item 1 rather than a footnote: Dark is a complete 12-key palette, not a
stub. Every Light key has a counterpart, so it resolves silently instead of failing — Require
throws only on a missing key. An opt-in tester on a dark-mode machine sees an unreviewed UI
and has no way to know that is not the intended design, which makes their feedback misleading
as well.

Fix is one line at the top of FwAvaloniaApp.Initialize():

RequestedThemeVariant = ThemeVariant.Light;

Mirror it in PreviewHostApp so the two Initialize() bodies stay parallel as their comments
promise.

The test must assert RequestedThemeVariant, not ActualThemeVariant. Under headless the
latter reports Light regardless, so a test written the obvious way passes even unfixed.

2. The enforcement check stays blocking — but it has to be trustworthy first

I am keeping token-hygiene as a hard CI failure. The scope is narrow and real, and a check
that only ever runs advisory tends to stay advisory. But a blocking check must not misdescribe
itself, and this one does, in five places plus a bug.

2a. It can silently stop checking. token-hygiene.ps1:70-81 sets
FW_TOKEN_HYGIENE_REPORTED=1, and any later invocation in the same job exits 0 before
scanning, regardless of -Advisory. Reorder the CI steps so any advisory run precedes the
build and the enforcing run becomes a no-op pass that reports success. This is the most
important fix in the item: an enforcement mechanism that can quietly disable itself is worse
than none, because it is trusted.

2b. Four documentation claims are false. build.ps1:128-129 ("CI reports violations as
warning annotations either way"), build.ps1:227-228 and test.ps1:129-130 ("in CI it only
annotates the pull request") — CI.yml:73 runs -TokenHygiene with an explicit
exit $LASTEXITCODE and no continue-on-error, and annotations are emitted only under
$Advisory (token-hygiene.ps1:62), so CI emits none and hard-fails. test.ps1:46-47 omits
that test.ps1:131 force-runs it whenever CI=true. TokenHygiene.psm1:282-285 says comments
are "masked only when the comment is the whole line's content", which is not what the code
does. AGENTS.md is the only one that matches reality.

2c. ADR 0001's enforcement paragraph describes a feature that does not exist. It states the
check "requires every value in the FieldWorks token files to be either a Semi alias or a
literal on a declaration line with a written justification comment — a literal with no comment
... fails". The entire implementation is TokenHygiene.psm1:360:
if ($line -match '\bx:Key\s*=') { continue }. No comment is required or checked. Someone
reading the ADR would believe the token dictionaries are policed when they are the least
policed files in scope.

2d. Close the worst holes. I ran the scanner against fixtures; every one of these passes
clean today:

<Border x:Key="X" Background="#FF0000" Margin="40" Padding="12,8"/>   (x:Key skips the line)
<Border Background="#00FF00"/> <!-- note -->                          (<!-- masks the line)
Opacity = 0.45,                                                       (not in the property list)
Padding = new Thickness(radio * 0.45)                                 (arithmetic evades)
Height = (double)18   /   MinWidth = 160.0m                           (cast/suffix evades)
var col = Avalonia.Media.Brushes.Red;                                 (lookbehind exempts it)
<Border Margin="8 4 8 4"/>                                            (numeric check is comma-only)
<Grid RowDefinitions="40,Auto" ColumnDefinitions="220,*"/>            (names not listed)

The x:Key and comment-masking ones matter most because they skip the entire line, and
TokenHygiene.Tests.ps1:204,209,323 encode that behaviour as intended. Narrowing both to the
matched declaration rather than the whole line, adding Opacity/Margin/Padding/
BorderThickness/CornerRadius to the C# property list, and accepting space-separated
Thickness values would close most of it. I am not asking for a perfect scanner — I am asking
that it not be defeated by appending a comment.

2e. "Whole-tree, no grandfathering" is 170 files out of 2309 under Src. That is a fine
scope; it is just not what the phrase says. Please state the real scope in the ADR and the body.

3. One-use tokens belong next to their view — the check already allows this

DialogTheme.axaml:97-116 hoists roughly twenty per-dialog constants into the shared dialog
dictionary, and the file's own comment apologises for it: "one-off, content-driven, but still
named for the token-hygiene gate."

That apology is unnecessary, because the check does not require it. I verified this by running
the scanner over a fixture: a value declared in a view's own <UserControl.Resources> is not
flagged (the declaration line contains x:Key=), and consuming it via {StaticResource} is
not flagged either. Only the literal usage trips. So a one-use value can live in the file that
uses it.

All six of the clearest offenders are consumed from exactly one .axaml and never from C#:

Please move them back and write the rule down somewhere durable: a value used by one view
lives in that view's own Resources; a value shared by two or more views, or consumed from
C#, goes in the shared dictionary. The two set on a root element referencing its own
Resources are worth a quick confirm rather than an assumption.

That restores "shared" to meaning shared, and removes the only place where the check is
visibly distorting the design.

4. Account for the values that changed, and re-measure two colours

The body says fwGroupBox "is the one real visual change". Seven values moved:

plus three new: WsAbbrevMaxWidth 120, HotlinkBrush #0064FA, DisabledOptionBrush
#808080. FwColorTokenResolutionTests.cs:28,34 assert two of them, so they are intended —
but a 56% wider label column and a doubled writing-system gutter are not "no visual change",
and a reviewer reading the body would not go looking.

Please list each with a one-line reason under "Where to look". ValidationErrorBrush
especially: muted brick to vivid orange-red is a large perceptual jump, and the comment at
FwAvaloniaDensity.cs:205-208 says danger "is exactly what that role means, with no
FieldWorks-specific divergence to justify" — while FwColorTokens.axaml elsewhere declines
exactly this kind of drift ("so the measured value stays").

And the label colours need a real measurement, not a reworded claim. main
described #6666B8 as the "legacy label hue from the committed baseline pixels"; the branch
describes #696969 as "measured from the legacy baseline". Both claim the same source for
colours that are nowhere near each other (blue-violet versus grey; steel blue versus
near-black), FwColorTokens.axaml repeats the new claim, and ADR 0001 then cites those
comments as its provenance — so the evidence is circular and one half of it is false. You have
the baseline PNGs committed; please re-derive both values, state the method, and correct
whichever comment is wrong. For infrastructure like this the dictionary is the design
record, and the next person will treat whatever it says as measured fact.

5. Vendor-supplied strings must end up in Crowdin

What is here today is a net improvement, and worth saying so first. The only Ursa types used
anywhere are Form and FormItem (DataTree.cs), which render no text, and FwSemiLocale's
own docstring explains the real bug it prevents — both vendor themes reset to zh-CN on an
unrecognised locale, so without this class an Arabic user would get Chinese context menus.
Mapping the other locales to en-US is the right call.

The direction still needs to change. Semi now owns the wording of user-visible chrome — the
built-in TextBox context menu and validation furniture, in dialogs that do use text-bearing
controls (ChooserDialogView, CreateFeatureDialogView, EntryGoDialogView,
LexOptionsDlgView). A third-party vendor decides FieldWorks' vocabulary for six of the 29
locales in Installer.legacy.targets:527 and leaves the other 23 in English.

These strings need to come from a FieldWorks-owned .resx translated through Crowdin.
crowdin.json already globs Src/**/*.resx, so a resource file under Src/ flows to all
shipped locales with no config change — the work is enumerating Semi's localised keys and
overriding them. If that does not land in this PR, please record it as a Jira issue before
merge and reference it here, and label FwSemiLocale in its own summary as the interim
measure it is rather than the destination.

Either way, add a test pinning the locale lists against the shipped packages. They are
hand-transcribed from a version comment ("v11.3.14", "v1.15.1"), FwSemiLocale has no test
coverage at all, and drift in the wrong direction silently reintroduces the zh-CN default this
class exists to prevent.

6. Fix the layering inversion

FwAvalonia.csproj:83,93,97 feed ..\FwAvaloniaDialogs\DialogTheme.axaml into
GenerateFwTokenKeys, and FwAvaloniaDialogs.csproj:55 project-references FwAvalonia. So the
foundation's generated public API is determined by a file inside its own dependent. This
contradicts FwAvaloniaTheme.csproj:6-12, whose stated reason for existing is that the two
projects "share ONE token source without either depending on the other".

Concretely: GenerateTokenKeys.cs:114-116 throws InvalidDataException on an identifier
collision, so a Dialogs-only edit can fail the foundation's compile; and
FwAvaloniaApp.Initialize never merges DialogTheme.axaml, so the foundation publishes 23
Dialog* constants for keys its own app never registers.

The only consumer is CompactDialogStyles.cs (5 Dialog*Value uses), which is dialog styling
living in the foundation. Moving DialogTheme.axaml into FwAvaloniaTheme, or
CompactDialogStyles into Dialogs, removes the inversion entirely.

7. labelMaxWidth ignores the actual column width

DataTree.cs:439-440 computes labelMaxWidth from the token LabelColumnWidth (150) while
the real grid column comes from the host-supplied getLabelColumnWidth() (:92). This use is
new in this PR. Drag the splitter narrower than 150 and label wrapping stays capped at the
token, not the column. Either derive it from the same source the column uses, or say why the
token is correct here.

8. Pin the Ursa workarounds with tests

DataTree.cs fights Ursa's ControlTheme in three places — :107-110 (overriding
HorizontalAlignment=Left), :113-119 (a scoped style beating FormItem's Margin="0 8"),
:453-456 (local FontWeight.Normal beating a bold DynamicResource binding) — plus
:121-123/:152 depending on FormItem honouring only an absolute LabelWidth. All four
depend on undocumented internals of a 1.x dependency.

The only Ursa-aware test (DetailCustomFieldRenderingTests.cs:70) asserts none of them, and
VisualParityAndDensityTests.cs:141 asserts a constant rather than a rendered margin. An Ursa
upgrade that changes any of these regresses layout silently. Characterization tests asserting
the resolved alignment, margin and font weight would fail loudly instead, which is what you
want on a dependency you do not control.

9. Housekeeping

• Stranded Fluent. FluentTheme is referenced by zero code on the branch but still
  package-referenced in FwAvalonia.csproj:37, FwAvaloniaTests.csproj:28,
  FwAvaloniaDialogs.csproj:35, FwAvaloniaDialogsTests.csproj:23,
  FwAvaloniaPreviewHost.csproj:23, plus the pin at Directory.Packages.props:192. Drop them —
  otherwise a Fluent DynamicResource can silently resolve again later.
• PrivateAssets is backwards. Only FwAvalonia.csproj:39-41 marks Semi/Ursa
  PrivateAssets="all" — but FwAvalonia's runtime code needs Ursa, so the dependency does not
  flow and every consumer must redeclare it or hit a runtime FileNotFoundException. The other
  four projects omit it. Pick one contract deliberately.
• VisualSnapshotTests.cs:105-114 (DetailEditView_AtWindowWidth_RendersCleanly) asserts
  nothing — it captures and returns, where the test above it calls
  DialogLayoutAssert.AssertNoCrowding. It cannot fail on a rendering defect and it inflates
  the 647-passed figure.
• The word "gate". 22 newly-authored uses across AGENTS.md, build.ps1, test.ps1,
  TokenHygiene.psm1, token-hygiene.ps1 and the three ADRs, plus the filename
  0002-whole-tree-token-hygiene-gate.md. Please use "check"/"checker". This is all new text,
  so there is no existing-prose exemption.
• Broken ADR links. The body's three links point at .../blob/semi-avalonia/docs/adr/...;
  the files are at Docs/adr/..., and GitHub blob paths are case-sensitive.
• Docs/adr/ is a third location. Docs/architecture/ and openspec/ already exist for
  this, and AGENTS.md names Docs/lessons/README.md as the durable-lessons index. Three
  decisions of this weight should land in an existing system, or the new one should be
  explained.
• Docs/adr/0002's central justification is an uncited appeal to "current design-token
  literature" (twice). For a decision that changes build policy for every contributor, name the
  source.
• New group-box captions with no WinForms twin — FwAvaloniaDialogsStrings.cs:41-45,56-57
  adds "Interface", "Startup", "Automatic Updates". The dialog-update skill requires approved
  divergences from the WinForms twin to be recorded in the conversion's Jira issue; no LT-
  reference appears in the branch.

Questions, not change requests

• Brush identity. These properties now return the shared, mutable SolidColorBrush
  from the dictionary, where main returned immutable Brushes.* singletons. You reason about
  this for TransparentBrush (FwAvaloniaDensity.cs:230-236) but not for SliceRuleBrush,
  SectionRuleBrush or PickerBorderBrush. Is anything relying on reference equality or
  mutating one?
• Does FwBuildTasks need Avalonia? FwBuildTasks.csproj:26-27 takes the dependency solely
  for Thickness.Parse (GenerateTokenKeys.cs:127-133,180-188), which puts Avalonia.Base and
  its closure into BuildTools/ for every build in the repo. Parsing one to four
  comma-or-space-separated doubles by hand is a few lines.
• Absolute paths in the generated file. GenerateTokenKeys.cs:141,146 writes the raw input
  paths into the header, and those come from $(MSBuildProjectDirectory)\..\..., so
  GeneratedTokenKeys.g.cs differs byte-for-byte between machines. It is gitignored so the
  impact is small, but a repo-relative path is a one-liner.
• L10NSharp jumps ten betas (SilVersions.props:22, beta0004 to beta0014) inside a theming
  PR, with the body noting only that live language switching was investigated and dropped. What
  else moved in those ten?
• FwSemiDensity.cs:35-39 computes radio * 0.45 while its own adjacent comment cites
  Semi's ratio as "~0.375". Which is right?

Noted, not asked for

• High contrast. Not a regression — 150 WinForms files still use SystemColors and track
  the OS scheme. But Avalonia maps a high-contrast scheme onto Light or Dark by whether its name
  contains "White", so a High Contrast Black user lands in that unreviewed Dark palette. Pinning
  Light (item 1) does not fix high contrast; it makes the failure consistent and reviewed rather
  than arbitrary. Real support is out of scope here and worth its own ticket.
• Dependency licences. Semi and Ursa are both MIT and compatible, and this PR records
  neither — but the repo has no NuGet-licence convention at all (Docs/architecture/dependencies.md
  is about repo dependencies, and no NOTICE file is tracked), so this PR is consistent with
  existing practice. Raising it as a gap for someone to close, not as something you introduced.

Comments

FwAvaloniaDensity.cs appends the same sentence — "Resolved from the shared FwAvaloniaTheme
token dictionary (DataTree.X) at point-of-use, after the Application has started" — to roughly
25 properties, beside code that already reads
FwThemeResources.RequireDouble(GeneratedTokenKeys.DataTree_X). It restates the code, it is
HOW rather than WHAT, it names the collaborator, and it duplicates the type-level precondition
in every member. One statement on the type, none on the members.

Also: cross-file pointers (FwColorTokens.axaml:11-12, TokenHygiene.psm1:15-16); absence
narration (FwColorTokens.axaml:10-12, FwSemiDensity.cs:10-15, LexOptionsDlgView.axaml:34-38
and :115-119); DialogThemeBootstrap.cs:65-68, a four-line comment explaining why no style is
added, followed by nothing — delete it; a finding reference at DataTree.cs:121 ("Viewing
parity (11.15)"); and consumer instructions in FwThemeResources.cs:12-25. FwThemeResources
should carry an <exception> tag for the InvalidOperationException its whole design rests on
— which is also the one path Codecov shows uncovered.

The per-key rationale comments in DataTreeTokens.axaml and FwColorTokens.axaml are the good
ones: real WHY, one or two sentences, correctly using single hyphens inside XML comments. Keep
those.

Finally, dozens of the rewrapped comments break mid-phrase leaving orphan one-word lines
(FwAvaloniaApp.cs:17-18, FwThemeResources.cs:14-19, FwSemiDensity.cs:26-29,
DialogTheme.axaml:71-74, DialogLayoutAssert.cs:21-23, which also loses its bullet
indentation). Not a rule violation, but it reads as machine-mangled throughout.